Inside Macintosh: QuickDraw GX Printing /

Chapter 3 - Page Formatting and Dialog Box Customization / About Page Formatting and Dialog Box Customization

Dialog Box Customization

QuickDraw GX allows your application to customize print dialog boxes, typically, by adding panels. A panel is a portion of an expanded dialog box that presents additional printing options for users. For example, you may allow the user to specify custom margins in a panel you add to the Page Setup dialog box or the Custom Page Setup dialog box. Figure 3-8 shows the expanded Custom Page Setup dialog box with two panels, the General panel and the "My override" panel. The contents of the General panel are shown in Figure 3-8.

Figure 3-8 The expanded Custom Page Setup dialog box with two panels

QuickDraw GX stores a user's responses to most default dialog items in collection objects. Your application can use collection objects to store information from panels you have added to dialog boxes. For information about storing items in collection objects and retrieving them, see "Using Printing-Related Collection Objects" beginning on page 3-27.

Note

If several applications want to provide the same option in the same panel, it may be better to implement the panel in a printing extension. For more information about printing extensions, see the printing extensions chapter of Inside Macintosh: QuickDraw GX Printing Extensions and Drivers.

To create a panel, you must define a panel resource (gxPrintPanelType), as described in the next section. You may also define an extended item list resource (gxExtendedDITLType) that defines how to respond to user actions, such as clicking a button, while the panel is on the screen. This resource is described in the section "Automating Panel Events" beginning on page 3-25.

Messages are used to notify the application when a print dialog box is about to be displayed. This allows you to load the panel from the resource before the dialog box is displayed. The functions that invoke these messages are shown in Table 3-1.

Table 3-1 Functions that enable dialog box panels

Function	Description
GXJobPrintDialog	Displays the Print dialog box
GXJobDefaultFormatDialog	Displays the Page Setup dialog box
GXFormatDialog	Displays the Custom Page Setup dialog box

Your application typically takes these steps to enable a panel when the user chooses a menu item that brings up a dialog box:

1. Call the appropriate function, such as GXJobPrintDialog if the user chose the Print menu item from the File menu.
2. Respond to the message, such as gxJobPrintDialog, by invoking your override function; for example, MyJobPrintDialog. This response was set up by the call to GXInstallApplicationOverride to set up the application as a message handler.
3. Set up the panel and call GXSetupDialogPanel to display it. These actions are performed by the override function.
4. Forward the message. This action is also performed by the override function.

For an overview of how messages allow you to display a panel in a print dialog box, see the chapter "Introduction to Printing With QuickDraw GX" in this book.

To forward a message, you call one of the functions in Table 3-2.

Table 3-2 Functions that forward a dialog box message

Function	Description
Forward_GXJobPrintDialog	Forwards the gxJobPrintDialog message
Forward_GXJobDefaultFormatDialog	Forwards the gxJobDefaultFormatDialog message
Forward_GXFormatDialog	Forwards the gxFormatDialog message

You pass exactly the same arguments to the forwarding function as those with which your override function was called. For an example of setting up a custom dialog box with an added panel and forwarding a message, see the section "Adding Panels to Dialog Boxes" beginning on page 3-67. For information about how to forward other messages, see the Message Manager chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

The Dialog Box Panel Resource

A panel resource defines a panel. It specifies the following information:

• The panel's name, such as My override. The name appears in the list of panels for an extended dialog box, under the panel's icon.
• The script used to display the panel, such as smRoman.
• The resource of the 'DITL' resource that defines the items in the panel.
• The resource ID of the icon to display in the extended dialog box.

Listing 3-1 shows the structure of a panel resource.

Listing 3-1 A panel resource definition template

type gxPrintPanelType {
   pstring[31];   /* name */
   integer Script;/* international script */
   fill word;     /* long word reserved for future use */
   fill word;     /* long word reserved for future use */
   integer;       /* the icon id */
   integer;       /* the ditl id */
};

Responding to Panel Events

QuickDraw GX handles events for its default panels automatically. If you change a default panel or you add another one, you may need to override the messages that QuickDraw GX sends in order to process the items that you added.

If an event occurs while a panel is displayed, QuickDraw GX sends a gxFilterPanelEvent message. If you want to filter the event, you can override this message by installing a handler for it and by specifying a function that matches the prototype defined for GXFilterPanelEvent on page 3-124.

If you do not need to filter the event, you may choose to handle the event in your code, you may automate the handling of the event, or you may do both. Events that you need to handle in some way include mouse clicks on radio buttons or checkboxes, choosing an item from a pop-up menu, and keystrokes in editable text fields.

To handle the event in your application code, you install an override for the gxHandlePanelEvent message. You can override this message by installing a handler for it and specifying a function that matches the prototype defined for GXHandlePanelEvent on page 3-123.

For information about messages and how to override them, see the chapter "Introduction to Printing With QuickDraw GX" in this book. For an example of installing an override function, see the chapter "Core Printing Features" in this book. For information about automatically handling panel events, see the next section.

Automating Panel Events

You can allow QuickDraw GX to automatically respond to selections in dialog box panels without you writing additional application code. QuickDraw GX provides an extended item list (gxExtendedDITLType) resource that loads values or settings of items and responds to changes to items in an item list ('DITL') resource. The item types for which QuickDraw GX can load values or settings and respond to changes in them include

• radio buttons
• checkboxes
• pop-up menus
• editable text in strings; the strings may represent characters, integers, and real numbers

QuickDraw GX obtains the values or settings from items in the job and format collections and responds to changes, by updating the information in these items, when the changes are confirmed. If the panel is part of the Print dialog box, the collection item must be in the job collection. If the panel is part of the Page Setup or Custom Page Setup dialog box, the collection item must be in the format collection.

For example, as a panel is displayed, an extended item resource specifies the collection item to use to set a group of radio buttons. If a user clicks on an unselected radio button, QuickDraw GX deselects the previously highlighted button and highlights the chosen one. When the user closes the panel and confirms the settings (for example, by clicking the OK button), the items specified by the extended item resource are placed back in their collections. If the user cancels the panel, the collection items are not changed.

The processing for checkboxes is similar. If the checkbox is not checked, QuickDraw GX checks it; if it is checked, QuickDraw GX unchecks it. Editable text is checked when the panel is closed and confirmed.

QuickDraw GX uses the resource IDs of the extended item list resource and 'DITL' resources to determine which extended item list to associate with the item list. If both kinds of resources have the same ID, they are used together. Specifically, when an open-panel (gxPanelOpenEvt) message is sent in response to the user choosing a panel in a dialog box, QuickDraw GX uses the extended item list resource that corresponds to the panel's 'DITL' resource to load and set the items. (Recall from the previous section that the panel resource specifies a 'DITL' resource.)

Listing 3-2 shows the extended item resource definition for editable text that represents a real number.

Listing 3-2 The extended item list resource definition template

#define  xdtlRadioButtons     0
#define  xdtlCheckBox         1
#define  xdtlEditTextInteger  2
#define  xdtlEditTextReal     3
#define  xdtlEditTextString   4
#define  xdtlPopUp            5

type gxExtendedDITLType {
...
         case EditTextReal:
            key      integer = xdtlEditTextReal;
            literal  longint;    /* 4 byte id for storage in job 
                                    object or format object */
                     longint;    /* numerical id for storage in 
                                    job object or format object */
                     integer;    /* offset in bytes into the item
                     byte;       /* corresponding ditl item */
                     byte;       /* 0 = dont select, 1 = select
                     pstring[15];/* low bound - nil means 'I 
                                    don't care' */
                     pstring[15];/* high bound - nil means 'I 
                                    don't care' */
...
      };
   };

There are common fields for each item type supported by an extended item list resource:

• The tag ID, such as gxPrintingTagID for QuickDraw GX defined tags.
• The ID of the collection item, such as gxFormatHalftoneTag.
• The offset into the collection item. The offset allows you to specify several values, such as the settings for checkboxes, in the same item.
• The corresponding item in the 'DITL' resource, starting with 1.

The remaining fields depend on the kind of data. For real number editable text, the fields specify the following:

• Whether or not to highlight the field's contents when the panel is displayed; 0 specifies do not highlight, 1 specifies to highlight.
• The lowest possible value for range checking. A nil string specifies no lower bound.
• The highest possible value for range checking. A nil string specifies no upper bound.

If a user enters data that does not conform to the specified format or specifies a number that is out of range, the text item inverts, and a system beep alerts the user to the problem when the user attempts to leave the field.

For the definitions of other kinds of fields, see "The Extended Item List Resource" on page 3-128. For an example of specifying an extended item list resource, see "Setting Up Dialog Box Resources" on page 3-70.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help